---
title: "OpenTelemetry Exporter | Tracing | Observability"
description: "Send traces to any OpenTelemetry-compatible observability platform"
---

# OpenTelemetry Exporter

The OpenTelemetry (OTEL) exporter sends your traces to any OTEL-compatible observability platform using standardized [OpenTelemetry Semantic Conventions for GenAI](https://opentelemetry.io/docs/specs/semconv/gen-ai/). This ensures broad compatibility with platforms like Datadog, New Relic, SigNoz, MLflow, Dash0, Traceloop, Laminar, and more.

:::info Looking for bidirectional OTEL integration?

If you have existing OpenTelemetry instrumentation and want Mastra traces to inherit context from active OTEL spans, see the [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel) instead.

:::

## Installation

Each provider requires specific protocol packages. Install the base exporter plus the protocol package for your provider:

### For HTTP/Protobuf Providers (SigNoz, New Relic, Laminar, MLflow)

```bash npm2yarn
npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-proto
```

### For gRPC Providers (Dash0)

```bash npm2yarn
npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-grpc @grpc/grpc-js
```

### For HTTP/JSON Providers (Traceloop)

```bash npm2yarn
npm install @mastra/otel-exporter@beta @opentelemetry/exporter-trace-otlp-http
```

## Provider Configurations


### MLflow

[MLflow](https://mlflow.org/docs/latest/genai/tracing/integrations/listing/mastra) supports native Mastra tracing through its OTLP endpoint at `/v1/traces`. Use the `custom` provider with HTTP/Protobuf and include the experiment header so traces land in the correct MLflow experiment:

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    custom: {
      endpoint: `${process.env.MLFLOW_TRACKING_URI}/v1/traces`,
      protocol: "http/protobuf",
      headers: {
        "x-mlflow-experiment-id": process.env.MLFLOW_EXPERIMENT_ID,
      },
    },
  },
})
```

### Dash0

[Dash0](https://www.dash0.com/) provides real-time observability with automatic insights.

```typescript title="src/mastra/index.ts"
import { Mastra } from "@mastra/core";
import { Observability } from "@mastra/observability";
import { OtelExporter } from "@mastra/otel-exporter";

export const mastra = new Mastra({
  observability: new Observability({
    configs: {
      otel: {
        serviceName: "my-service",
        exporters: [
          new OtelExporter({
            provider: {
              dash0: {
                apiKey: process.env.DASH0_API_KEY,
                endpoint: process.env.DASH0_ENDPOINT, // e.g., 'ingress.us-west-2.aws.dash0.com:4317'
                dataset: "production", // Optional dataset name
              },
            },
            resourceAttributes: {
              // Optional OpenTelemetry Resource Attributes for the trace
              ["deployment.environment"]: "dev",
            },
          }),
        ],
      },
    },
  }),
});
```

:::info

Get your Dash0 endpoint from your dashboard. It should be in the format `ingress.{region}.aws.dash0.com:4317`.

:::

### SigNoz

[SigNoz](https://signoz.io/) is an open-source APM alternative with built-in Tracing support.

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    signoz: {
      apiKey: process.env.SIGNOZ_API_KEY,
      region: "us", // 'us' | 'eu' | 'in'
      // endpoint: 'https://my-signoz.example.com', // For self-hosted
    },
  },
});
```

### New Relic

[New Relic](https://newrelic.com/) provides comprehensive observability with AI monitoring capabilities.

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    newrelic: {
      apiKey: process.env.NEW_RELIC_LICENSE_KEY,
      // endpoint: 'https://otlp.eu01.nr-data.net', // For EU region
    },
  },
});
```

### Traceloop

[Traceloop](https://www.traceloop.com/) specializes in LLM observability with automatic prompt tracking.

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    traceloop: {
      apiKey: process.env.TRACELOOP_API_KEY,
      destinationId: "my-destination", // Optional
    },
  },
});
```

### Laminar

[Laminar](https://www.lmnr.ai/) provides specialized LLM observability and analytics.

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    laminar: {
      apiKey: process.env.LMNR_PROJECT_API_KEY,
      // teamId: process.env.LAMINAR_TEAM_ID, // Optional, for backwards compatibility
    },
  },
});
```

### Custom/Generic OTEL Endpoints

For other OTEL-compatible platforms or custom collectors:

```typescript title="src/mastra/index.ts"
new OtelExporter({
  provider: {
    custom: {
      endpoint: "https://your-collector.example.com/v1/traces",
      protocol: "http/protobuf", // 'http/json' | 'http/protobuf' | 'grpc'
      headers: {
        "x-api-key": process.env.API_KEY,
      },
    },
  },
});
```

## Configuration Options

### Complete Configuration

```typescript
new OtelExporter({
  // Provider configuration (required)
  provider: {
    // Use one of: dash0, signoz, newrelic, traceloop, laminar, custom
  },

  // Export configuration
  timeout: 30000, // Export timeout in milliseconds
  batchSize: 100, // Number of spans per batch

  // Debug options
  logLevel: "info", // 'debug' | 'info' | 'warn' | 'error'
});
```

## OpenTelemetry Semantic Conventions

The exporter follows [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai), ensuring compatibility with observability platforms:

### Span Naming

- **LLM Operations**: `chat {model}`
- **Tool Execution**: `execute_tool {tool_name}`
- **Agent Runs**: `invoke_agent {agent_id}`
- **Workflow Runs**: `invoke_workflow {workflow_id}`

### Key Attributes

- `gen_ai.operation.name` - Operation type (chat, tool.execute, etc.)
- `gen_ai.provider.name` - AI provider (openai, anthropic, etc.)
- `gen_ai.request.model` - Model identifier
- `gen_ai.input.messages` - Chat history provided to the model
- `gen_ai.output.messages` - Messages returned by the model
- `gen_ai.usage.input_tokens` - Number of input tokens
- `gen_ai.usage.output_tokens` - Number of output tokens
- `gen_ai.request.temperature` - Sampling temperature
- `gen_ai.response.finish_reasons` - Completion reasons

## Protocol Selection Guide

Choose the right protocol package based on your provider:

| Provider  | Protocol      | Required Package                           |
| --------- | ------------- | ------------------------------------------ |
| Dash0     | gRPC          | `@opentelemetry/exporter-trace-otlp-grpc`  |
| SigNoz    | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| New Relic | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Traceloop | HTTP/JSON     | `@opentelemetry/exporter-trace-otlp-http`  |
| Laminar   | HTTP/Protobuf | `@opentelemetry/exporter-trace-otlp-proto` |
| Custom    | Varies        | Depends on your collector                  |

:::warning

Make sure to install the correct protocol package for your provider. The exporter will provide a helpful error message if the wrong package is installed.

:::

## Troubleshooting

### Missing Dependency Error

If you see an error like:

```
HTTP/Protobuf exporter is not installed (required for signoz).
To use HTTP/Protobuf export, install the required package:
  npm install @opentelemetry/exporter-trace-otlp-proto
```

Install the suggested package for your provider.

### Common Issues

1. **Wrong protocol package**: Verify you installed the correct exporter for your provider
2. **Invalid endpoint**: Check endpoint format matches provider requirements
3. **Authentication failures**: Verify API keys and headers are correct

## Using Tags

Tags help you categorize and filter traces in your observability platform. Add tags when executing agents or workflows:

```typescript
const result = await agent.generate({
  messages: [{ role: "user", content: "Hello" }],
  tracingOptions: {
    tags: ["production", "experiment-v2", "user-request"],
  },
});
```

Tags are exported as a JSON string in the `mastra.tags` span attribute for broad backend compatibility. Common use cases include:

- Environment labels: `"production"`, `"staging"`
- Experiment tracking: `"experiment-v1"`, `"control-group"`
- Priority levels: `"priority-high"`, `"batch-job"`

## Related

- [Tracing Overview](/docs/v1/observability/tracing/overview)
- [OpenTelemetry Bridge](/docs/v1/observability/tracing/bridges/otel)
- [OpenTelemetry Semantic Conventions for GenAI v1.38.0](https://github.com/open-telemetry/semantic-conventions/tree/v1.38.0/docs/gen-ai)
- [OTEL Exporter Reference](/reference/v1/observability/tracing/exporters/otel)
